import polars as pl
iucn = pl.read_csv(
"https://raw.githubusercontent.com/juba/pylifemap/main/data/iucn.csv"
)Usage
To create a Lifemap data visualization, you will have to follow these steps:
- Prepare and load your data,
- If needed, aggregate you data with an aggregation function
- Initialize a Lifemap object
- Add visualization layers
- show() or save() the result
Prepare your data
The date you want to visualize on the Lifemap tree of life must be in a pandas or polars DataFrame. They must contain at least observations (species) as rows, and variables as columns, and at least one column must contain the NCBI taxonomy identifier of the species.
pylifemap includes an example polars data file generated from The IUCN Red List of Threatened Species. It is a CSV file with the Red List category (in 2022) of more than 84000 species.
We can import it as a polars DataFrame with the following code:
If we display the resulting table, we can see that it only has two columns, one called taxid which contains the species identifiers, and another called status with the Red List category of each species:
iucn
shape: (84_981, 2)
| taxid | status |
|---|---|
| i64 | str |
| 651506 | "Data Deficient… |
| 2803960 | "Critically End… |
| 143610 | "Critically End… |
| 2760993 | "Least Concern" |
| 72259 | "Least Concern" |
| … | … |
| 337230 | "Least Concern" |
| 442623 | "Vulnerable" |
| 2303643 | "Critically End… |
| 442625 | "Critically End… |
| 442626 | "Least Concern" |
Initialize a Lifemap object
The next step is to create a new Lifemap object. To do this we have to pass it our DataFrame, as well as the name of the column with our taxonomy identifiers[^if your column is named “taxid” you can omit the taxid_col argument as it is its default value.]:
from pylifemap import Lifemap
Lifemap(iucn, taxid_col="taxid")<LifemapWidget>We could have passed other arguments such as the width and height of our visualization, either as a number of pixels or as a CSS units.
For example, the following intialization would make the visualization take the full available width, and an height of 800 pixels.
Lifemap(iucn, taxid_col="taxid", width="100%", height=800)Add visualization layers
After initializing our Lifemap object, we have to add visualization layers to create graphical representations. There are several different layers available:
| Layer | Description |
|---|---|
| layer_points | Displays each observation with a point. Radius and color can be dependent of an attribute in the DataFrame. |
| layer_lines | Using aggregated data, highlights branches of the tree by lines of varying width and color. |
| layer_donuts | Displays aggregated categorical data as donut charts. |
| layer_heatmap | Displays a heatmap of the observations distribution in the tree. |
| layer_screengrid | Displays the observations distribution with a colored grid with fixed-size cells.. |
To add a layer, we just have to call the corresponding layer_ method of our Lifemap object. For example, to add a points layer:
éLifemap(iucn, taxid_col="taxid").layer_points()We can add several layers by calling several methods. For example we could display a heatmap layer, and a points layer above it:
Lifemap(iucn, taxid_col="taxid").layer_heatmap().layer_points()Show or save the visualization
Just adding layers is not sufficient to see our visualization. For it to appear, we have to call the show() method:
Lifemap(iucn, taxid_col="taxid").layer_points().show()We can also save it to an HTML file which can be opened later in a browser by using the save() method:
Lifemap(iucn, taxid_col="taxid").layer_points().save("lifemap.html")Customize the layers
Each layer accepts a certain number of arguments to customize its appearance. For example we can change the radius and opacity of our points and make their color depend on their status value:
(
Lifemap(iucn, taxid_col="taxid")
.layer_points(fill_col="status", radius=3, opacity=0.5)
.show()
)Aggregate data
pylifemap provides several aggregation functions that allow to aggregate data along the branches of the tree:
| Function | Description |
|---|---|
| aggregate_count | Aggregates the number of children of each tree node. |
| aggregate_num | Aggregates a numerical variable along the tree branches with a given function (sum, mean, max…). |
| aggregate_freq | Aggregates the frequencies of the levels of a categorical variable. |
For example, we could filter out in our data set the species which have an “extinct” status:
iucn_extinct = iucn.filter(pl.col("status") == "Extinct")We can then aggregate their count along the branches with aggregate_count:
from pylifemap import aggregate_count
iucn_extinct_agg = aggregate_count(iucn_extinct)
iucn_extinct_agg
shape: (768, 2)
| taxid | n |
|---|---|
| i32 | u32 |
| 0 | 198 |
| 2759 | 198 |
| 3193 | 21 |
| 3268 | 1 |
| 3398 | 20 |
| … | … |
| 3036923 | 1 |
| 3041918 | 1 |
| 3055989 | 1 |
| 3072905 | 2 |
| 3076244 | 1 |
Finally, we can represent this new dataset with a lines layer.
(
Lifemap(iucn_extinct_agg)
.layer_lines(color_col="n", width_col="n", label="Extinct species")
.show()
)